# Chai

Chai is a project to reverse engineer the
[Mali](https://en.wikipedia.org/wiki/Mali_(GPU)) T-series of GPUs. It
focuses on the T760 which is found in the
[RK3288](https://en.wikipedia.org/wiki/RK3288) SoC. This SoC is notably
used in the Veyron design for Chromebooks, which are supported in
[Libreboot](https://libreboot.org).

Chai has its roots in [lima](https://limadriver.org/) by Luc Verhaegen
et al. Lima targets the older Mali cores; chai is for the newer cores
like its unreleased successor Tamil. At the time of writing, no code is
shared with lima, although limare was useful for illustrative purposes.
One of lima's authors, Connor Abbott, did release reverse-engineered
documentation for the [T6xx ISA](http://limadriver.org/T6xx+ISA/), which
will be used in chai, along with his
[disassembler](https://gitorious.org/open-gpu-tools/cwabbotts-open-gpu-tools.git).

Documentation about the GPU is in notes/. Supporting source code is in
src/. Source code is under the GPLv2.

## Roadmap

- [x] Basic understanding of the ecosystem
- [x] Fork of the [kernel module](https://notabug.org/cafe/oolong)
- [x] Basic userspace code to interact with the kernel module
- [x] Basic fuzzing from userspace
- [x] Ioctl [tracer](https://notabug.org/cafe/black)
- [ ] Polygon drawing
- [x] ...dump memory
- [x] ...decode memory
- [x] ...edit memory
- [ ] ...replay
- [ ] Textures
- [ ] ...dump memory
- [ ] ...decode memory
- [ ] ...edit memory
- [ ] ...replay
- [ ] Primitive shaders
- [x] ...dump memory
- [x] ...reverse ISA (thanks cwabbott!)
- [x] ...disassemble memory (ditto!)
- [ ] ...reassemble
- [ ] Complex shaders
- [ ] ...reverse entire ISA
- [ ] ...functional compiler
- [ ] ...optimising compiling
- [ ] Kernel interface
- [x] ...port to mainline (thanks phh!)
- [x] ...basic cleanup
- [ ] ...use native kernel interfaces
- [ ] ...upstreamed
- [ ] Mesa driver
- [ ] ...with toy programs and toy shaders
- [ ] ...with shader compiler
- [ ] ...with all commands supported
- [ ] ...upstreamed

This list is in flux as project requirements change.

## Legal aspects

The shim is free (GPLv2) and is modified for chai. No other ARM code is
used in chai.

Initial reverse engineering used a combination of fuzzing and reading
through the shim source code. Later notes observe communication between
the shim and the blob. A tracer was written that hooks into the shim
function `kbase_ioctl`, called for each message. It decodes the message
and dumps it to the console for inspection and replay.

The Mali Offline Shader Compiler may be useful for ISA reverse
engineering. See the [Lima
wiki](http://limadriver.org/Mali_Offline_Shader_Compiler/) which
discusses legal aspects here.

None of chai's authors are or were affiliated with ARM Limited.

## Name

Chai, oolong, and black are for T GPUs. It's a joke. Get it?
